SQL Server 2008 : Database Mail - Using SQL Server Agent Mail

Job Mail Notifications

The following sections show an example in which you create a SQL Server Agent Mail operator that SQL Server Agent will notify when a job completes.

Creating an Operator

First, you need to create an operator. To do so, using the Object Browser, you expand the SQL Server Agent node and then right-click the Operators folder and select New Operator. Then you should name this new operator Test Database Mail Operator and provide an email address for testing purposes in the Email Name text box. You can use any valid email address you can access with your email client software. You click OK to save the new operator.

Enabling SQL Agent Mail

Next, you need to enable SQL Server Agent to use Database Mail. You right-click the SQL Server Agent node and then select Properties. On the left side of the Properties dialog that appears (see Figure 1), you click the Alert System link. Under the Mail Session group, you check the Enable Mail Profile check box. In the Mail System drop-down list, you select Database Mail (this is also the place where you can choose SQL Mail, if you desire). In the Mail Profile drop-down list, you select the default SQL 2008 profile you created earlier and then click OK. By doing this, you are telling SQL Server Agent to use the SMTP servers in your default profile to send email. You need to restart SQL Server Agent by using the right-click menu.

Figure 1. Using the SQL Server Agent Properties dialog to configure Database Mail.

Creating the Job

Next, you need to create the job. You begin by right-clicking the Jobs folder and then selecting New Job. You should name the job Database Mail Test Job and select an owner. Then you should check the Enabled check box near the bottom of the dialog and click the Steps link on the left side of the dialog. Next, you click the New button and add a step named Test Mail Step 1. You should leave the type as Transact-SQL and then change the database selection to AdventureWorks2008. In the Command text box, you enter the following code:

RAISERROR('This is simply a test job.', 10, 1)

Next, you click the Advanced link on the left side of the dialog, and in the On Success Action drop-down list, you select Quit the Job Reporting Success. Then you click the Notifications link on the left side of the dialog. Next, under Actions to Perform When the Job Completes, you check the Email check box and select the operator you just created. From the drop-down to the right, you select When the Job Completes and then click OK to save the job.

Testing the Job-Completion Notification

To test the email configuration and notification you just set up, you right-click the job name under the Jobs folder and then select Start Job. If everything is set up properly, an email message appears in your inbox, indicating the job’s successful completion. Its body text might look something like this:

JOB RUN:    'Database Mail Test Job' was run on 5/7/2009 at 8:37:22 PM
DURATION:    0 hours, 0 minutes, 0 seconds
STATUS:   Succeeded
MESSAGES:    The job succeeded.  The Job was invoked by User [TestUser].
    The last step to run was step 1 (Test Mail Step 1).

Alert Mail Notifications

As another example, in the following sections, you’ll create a simple user-defined alert that you can trigger directly from T-SQL script.

Creating an Alert

You start by creating an alert. To do this, you use the Object Browser to expand the SQL Server Agent node; then you right-click the Alerts node and select New Alert. In the Alert Properties dialog that appears (see Figure 2), you name the new alert Database Mail Test Alert and make sure the Enabled check box is checked. For the Event type, you leave the selection on SQL Server Event Alert. Under Event Alert Definition, select AdventureWorks2008 from the Database Name drop-down list, and then click the Severity option button and choose 010 - Information. Next, check the Raise Alert When Message Contains check box and type the phrase This is a Test in the Message Text text box.

Figure 2. Creating a SQL Server event alert with a Database Mail notification.

On the left side of the alert properties dialog, you click the Response link. Then you check the Notify Operators check box and, in the Operator list, check the Email check box to the right of the Test Database Mail Operator grid row. Finally, you click OK to close and save the new custom alert.

Testing the Alert Notification

To test your new alert notification, you open a new query window in SMSS and enter the following code:

USE AdventureWorks2008
go
RAISERROR('This is an alert mail test', 10, 1) WITH LOG
go
'This is an alert mail test'

Because you specified WITH LOG, this simple statement writes an event to the Windows Event log, which in turn triggers the alert because the database context, message text, and severity all match the conditions of the alert. An email message should have appeared in your inbox, indicating the alert’s successful triggering. This message should contain body text such as this:

DATE/TIME:    5/7/2009 9:00:45 PM
DESCRIPTION:    Error: 50000 Severity:  10 State: 1 This is an alert
    mail test
COMMENT: (None)
JOB RUN:    (None)